导入和导出文件

介绍

本节的目的是解释如何将外部文件格式导入到 CadQuery 中，以及如何从中导出文件。虽然外部文件格式可用于与其他软件交换 CAD 模型数据，但 CadQuery 目前不支持任何携带参数数据的格式。唯一完全参数化的格式是 CadQuery 自己的 Python 格式。以下是 CadQuery 支持的导入和导出文件格式的列表。

导入格式

• DXF

• STEP

导出格式

• DXF

• SVG

• STEP

• STL

• AMF

• TJS

• VRML

• VTP

• 3MF

• glTF

格式注释

• DXF（Drawing Exchange Format）对于导入复杂的二维轮廓非常有用，而使用 CadQuery 的二维操作创建这些轮廓可能会很繁琐。例如，铝挤压的二维轮廓通常以DXF格式提供。可以导入并拉伸它们以创建设计所需的拉伸长度。

• STEP 文件可用于与其他 CAD 和分析系统（例如 FreeCAD）交换模型数据。许多零件（例如螺钉）都有可用的 STEP 文件，可以在 CadQuery 装配体中导入和使用这些文件。

• STL、AMF 和 3MF 文件是基于网格的格式，通常用于增材制造（即 3D 打印）。AMF 和 3MF 文件支持更多功能，但不像 STL 文件那样得到普遍支持。

• TJS 是 ThreeJS 的缩写，是一种 JSON 网格格式，可用于在 Web 浏览器中显示 3D 模型。TJS 格式用于显示 CadQuery 文档中嵌入的 3D 示例。

• VRML 是一种基于网格的格式，用于在 Web 浏览器中表示交互式 3D 对象。

• VTP 是 VTK 库使用的基于网格的格式。

• glTF 是一种基于网格的格式，可用于在 Web 上查看模型。生成的 glTF 文件是二进制 (.glb) 还是文本 (.gltf) 由文件扩展名设置。

导入 DXF

可以使用该方法导入 DXF 文件importers.importDXF()。

将 DXF 文件加载到工作平面中
默认情况下导入所有图层。 提供一个包含图层列表和排除图层列表来选择图层。层名称不区分大小写。

Parameters

• filename (str) – 要导入的 DXF 文件的路径和名称

• tol (float) – 用于将边合并为线的容差

• exclude (List[str]) – 不导入的图层名称列表

• include (List[str]) – 要导入的图层名称列表

Return type

• Workplane

导入默认设置的 DXF 配置文件并在 CadQuery 脚本中使用它的代码如下所示。

import cadquery as cq
result = (
    cq.importers.importDXF("/path/to/dxf/circle.dxf").wires().toPending().extrude(10)
)

请注意使用Workplane.wires()和Workplane.toPending()方法使 DXF 轮廓可供后续操作使用。调用toPending()告诉 CadQuery 使边/线可用于链中调用的下一个建模操作。

导入 STEP

可以使用该方法导入STEP文件importers.importStep()（注意“Step”的大写）。除了要导入的文件路径之外，此方法没有任何参数。

import cadquery as cq
result = cq.importers.importStep("/path/to/step/block.stp")

导出 STEP

本节介绍将 CadQuery Workplane 对象导出到 STEP。要将程序集导出到 STEP，请参阅下一节。

默认

导出器模块处理将工作平面对象导出到 STEP。无需显式设置导出类型，因为它将根据文件扩展名确定。下面是一个例子。

# Create a simple object
box = cq.Workplane().box(10, 10, 10)

# Export the box
cq.exporters.export(box, "/path/to/step/box.step")

非默认文件扩展名

如果需要使用“stp”扩展名导出 STEP 文件，CadQuery 将抛出错误，指出它无法识别该文件扩展名。在这种情况下，必须指定导出类型。

# Create a simple object
box = cq.Workplane().box(10, 10, 10)

# Export the box
cq.exporters.export(box, "/path/to/step/box.stp", cq.exporters.ExportTypes.STEP)

# The export type may also be specified as a literal
cq.exporters.export(box, "/path/to/step/box2.stp", "STEP")

设置额外选项

将对象导出到 STEP 文件时可以设置其他选项。Shape.exportStep()有关可用选项的说明，请参阅方法或方法的文档Assembly.exportAssembly()。

# Create a simple object
box = cq.Workplane().box(10, 10, 10)

# Export the box, provide additional options with the opt dict
cq.exporters.export(box, "/path/to/step/box.step", opt={"write_pcurves": False})

# or equivalently when exporting a lower level Shape object
box.val().exportStep("/path/to/step/box2.step", write_pcurves=False)

将装配体导出到 STEP

可以将 CadQuery 程序集直接导出到 STEP。STEP 导出器有多个选项，可以更改导出的 STEP 文件在其他 CAD 程序中打开时的显示和操作方式。此处显示的所有装配导出方法都将保留装配中的颜色信息。

默认

CadQuery 程序集有一种Assembly.save()可以将程序集写入 STEP 文件的方法。下面显示了具有所有默认值的装配体导出示例。

import cadquery as cq

# Create a sample assembly
assy = cq.Assembly()
body = cq.Workplane().box(10, 10, 10)
assy.add(body, color=cq.Color(1, 0, 0), name="body")
pin = cq.Workplane().center(2, 2).cylinder(radius=2, height=20)
assy.add(pin, color=cq.Color(0, 1, 0), name="pin")

# Save the assembly to STEP
assy.save("out.step")

这将生成一个，嵌套自动生成的对象名称的 STEP 文件。每个装配对象的颜色将被保留，但为每个对象设置的名称将不会保留。

熔断器 Fused

下面将尝试创建单个融合形状，同时保留每个装配对象的名称和颜色信息。在某些情况下，实体的融合过程可能会导致性能问题，并且可能会改变实体的表面。

import cadquery as cq

# Create a sample assembly
assy = cq.Assembly()
body = cq.Workplane().box(10, 10, 10)
assy.add(body, color=cq.Color(1, 0, 0), name="body")
pin = cq.Workplane().center(2, 2).cylinder(radius=2, height=20)
assy.add(pin, color=cq.Color(0, 1, 0), name="pin")

# Save the assembly to STEP
assy.save("out.stp", "STEP", mode="fused")

# Specify additional options such as glue as keyword arguments
assy.save("out_glue.step", mode="fused", glue=True, write_pcurves=False)

命名

还可以使用 DEFAULT 或 FUSED 方法在 STEP 文件中设置顶级装配对象的名称。这是通过在调用之前设置程序集的 name 属性来完成的Assembly.save()。

assy = Assembly(name="my_assembly")
assy.save(
    "out.stp",
    cq.exporters.ExportTypes.STEP,
    mode=cq.exporters.assembly.ExportModes.FUSED,
)

如果未指定程序集名称，将使用 UUID 以避免名称冲突。

导出 SVG

SVG 导出器有多个选项，可用于实现所需的最终输出。这些选项如下。

• width - 结果图像的宽度（不适合基于高度）。

• height - 生成图像的高度（不适合基于宽度）。

• marginLeft - 文档左侧的插入边距。

• marginTop - 文档顶部的插入边距。

• projectionDir - 相机查看形状的方向。

• showAxes - 是否显示轴指示器，只有当projectionDir也处于默认值时才可见。

• strokeWidth - 绘制可见边缘的线的宽度。

• strokeColor - 绘制可见边缘的线条的颜色。

• hiddenColor - 绘制隐藏边的线条的颜色。

• showHidden - 是否显示隐藏线。

• focus - 如果指定，则使用位于指定距离的投影仪创建透视 SVG。

这些选项以字典形式传递给导出器，并且可以省略以强制使用默认选项创建 SVG。以下是设置和未设置选项的示例。
没有选项：

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.export(result, "/path/to/file/box.svg")

结果是：

请注意，导出器 API 从文件扩展名中找出格式类型。可以使用 显式设置格式类型exporters.ExportTypes。

以下是使用选项通过opt传入参数来更改生成的 SVG 输出的示例。

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.export(
    result,
    "/path/to/file/box_custom_options.svg",
    opt={
        "width": 300,
        "height": 300,
        "marginLeft": 10,
        "marginTop": 10,
        "showAxes": False,
        "projectionDir": (0.5, 0.5, 0.5),
        "strokeWidth": 0.25,
        "strokeColor": (255, 0, 0),
        "hiddenColor": (0, 0, 255),
        "showHidden": True,
    },
)

结果如下图所示：

使用附加选项导出会产生以下带透视的输出 SVG："focus": 25

导出 STL

将形状导出到指定的 STL 文件。

Parameters

• fileName ( str ) – 要写入 STL 输出的路径和文件名。

• tolerance( float ) – 线性偏转设置，限制曲线与其镶嵌之间的距离。将此值设置得太低会导致网格过大，从而消耗计算资源。将值设置得太高可能会导致网格的细节级别太低。默认值为 1e-3，这对于一系列情况来说是一个很好的起点。

• angularTolerance ( float ) – 角度偏转设置，限制折线中后续线段之间的角度。默认值为 0.1。

• ascii ( bool ) – 将文件导出为 ASCII (True) 或二进制 (False) STL 格式。默认为二进制。

• relative ( bool ) – 如果设置为True，公差将根据正在生成网格的边的大小进行缩放。默认为True。将此值设置为True可能会导致大型特征变得多面化，或者小型特征变得密集。

• parallel ( bool ) – 如果为 True，OCCT 将使用并行处理对形状进行网格划分。默认为 True。

Return type

• bool

对于更复杂的对象，可能需要对tolerance和angularTolerance进行一些实验，以找到能生成可接受网格的最佳值。

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.export(result, "/path/to/file/mesh.stl")

导出 AMF 和 3MF

AMF 和 3MF 导出器能够调整生成的网格的质量，并接受以下参数。

• fileName- 将 AMF 输出写入的路径和文件名。

• tolerance- 线性偏转设置，限制曲线与其镶嵌之间的距离。将此值设置得太低会导致网格过大，从而消耗计算资源。将值设置得太高可能会导致网格的细节级别太低。默认值为 0.1，对于一系列情况来说这是一个很好的起点。

• angularTolerance- 角度偏转设置限制折线中后续线段之间的角度。默认值为 0.1。

对于更复杂的对象，可能需要对tolerance和进行一些实验angularTolerance，以找到产生可接受的网格的最佳值。请注意，缺少颜色和材料参数。

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.export(result, "/path/to/file/mesh.amf", tolerance=0.01, angularTolerance=0.1)

导出 TJS

TJS (ThreeJS) 导出器生成一个 JSON 格式的文件，该文件描述 ThreeJS WebGL 渲染器的场景。第一个参数中的对象被转换为网格，然后形成场景的 ThreeJS 几何体。可以使用以下参数调整网格。

• fileName- 将 ThreeJS 输出写入的路径和文件名。

• tolerance- 线性偏转设置，限制曲线与其镶嵌之间的距离。将此值设置得太低会导致网格过大，从而消耗计算资源。将值设置得太高可能会导致网格的细节级别太低。默认值为 0.1，对于一系列情况来说这是一个很好的起点。

• angularTolerance- 角度偏转设置限制折线中后续线段之间的角度。默认值为 0.1。

对于更复杂的对象，可能需要对tolerance和进行一些实验angularTolerance，以找到产生可接受的网格的最佳值。

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.export(
    result,
    "/path/to/file/mesh.json",
    tolerance=0.01,
    angularTolerance=0.1,
    exportType=exporters.ExportTypes.TJS,
)

请注意，导出类型被明确指定为，TJS因为文件名使用的扩展名是.json. 如果使用了扩展.tjs ，CadQuery 将理解使用TJS导出格式。

导出 VRML

VRML 导出器能够调整生成的网格的质量，并接受以下参数。

• fileName- VRML 输出写入的路径和文件名。

• tolerance- 线性偏转设置，限制曲线与其镶嵌之间的距离。将此值设置得太低会导致网格过大，从而消耗计算资源。将值设置得太高可能会导致网格的细节级别太低。默认值为 0.1，对于一系列情况来说这是一个很好的起点。

• angularTolerance- 角度偏转设置限制折线中后续线段之间的角度。默认值为 0.1。

对于更复杂的对象，可能需要对tolerance和进行一些实验angularTolerance，以找到产生可接受的网格的最佳值。

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.export(
    result, "/path/to/file/mesh.vrml", tolerance=0.01, angularTolerance=0.1
)

导出 DXF

cadquery.occ_impl.exporters.dxf.DxfDocument用于将多个工作平面导出到 DXF 文档的一层或多层中。

选项

approx将cadquery.Workplane对象转换为 DXF 实体的近似策略：

None未应用近似值
"spline"所有样条近似为三次样条
"arc"所有曲线均近似为圆弧和直线段

tolerance将cadquery.Workplane对象转换为 DXF 实体的近似公差。请参阅近似策略。

doc_unitsEzdxf 文档/模型空间单位。

# 不带选项的 DXF 文档

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.exportDXF(result, "/path/to/file/object.dxf")
# or
exporters.export(result, "/path/to/file/object.dxf")

单位

默认 DXF 文档单位为毫米 ( doc_units = 4)。

文档单位可以设置为ezdxf 支持的任何单位。

# 单位设置为米的 DXF 文件

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.exportDXF(
    result,
    "/path/to/file/object.dxf",
    doc_units=6,  # set DXF document units to meters
)

# or

exporters.export(
    result,
    "/path/to/file/object.dxf",
    opt={"doc_units": 6},  # set DXF document units to meters
)

逼近策略

默认情况下，DXF 导出器将输出与 OpenCascade 内核所表示的样条线完全相同的样条线。遗憾的是，某些软件无法处理高阶样条线，导致 DXF 导入后曲线丢失。要解决此问题，请指定由以下选项控制的近似策略：

• approx- None，"spline"或者"arc"。"spline"所有样条曲线均以三次样条曲线近似。"arc"结果是所有用圆弧和线段近似的曲线。

• tolerance：可接受的近似误差，以文档/模型空间单位表示。默认为 0.001（对于英寸比例绘图为 1hou，对于毫米比例绘图为 1μm）。

# 带有用三次样条曲线近似的曲线的 DXF 文档
cq.exporters.exportDXF(result, "/path/to/file/object.dxf", approx="spline")

导出其他格式

其余导出格式不接受除文件名之外的任何附加参数，并且可以使用以下结构导出。

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.export(result, "/path/to/file/object.[file_extension]")

请务必使用正确的文件扩展名，以便 CadQuery 可以确定导出格式。如果有疑问，请回退到使用 显式设置类型exporters.ExportTypes。

例如：

import cadquery as cq
from cadquery import exporters

result = cq.Workplane().box(10, 10, 10)

exporters.export(result, "/path/to/file/object.dxf", exporters.ExportTypes.DXF)